home *** CD-ROM | disk | FTP | other *** search
/ HaCKeRz Kr0nlcKLeZ 1 / HaCKeRz Kr0nlcKLeZ.iso / emulator / coleco / colem.doc < prev    next >
Encoding:
Text File  |  1996-04-28  |  10.7 KB  |  266 lines
  1.  
  2.  
  3.                         ******* ColEm *******
  4.                  The Portable ColecoVision Emulator
  5.                              version 0.4
  6.  
  7.                          by Marat Fayzullin
  8.                       
  9.                       email: fms@freeflight.com
  10.                              IRC: RST38h
  11.                  WWW: http://www.freeflight.com/fms/
  12.  
  13.  
  14.  
  15.                        * NEW IN THIS VERSION *
  16.  
  17. o Z80 emulation sped up
  18. o Saving music into a file
  19. o Separate autofire for fire buttons
  20.  
  21.  
  22.  
  23.                            * INTRODUCTION *
  24.  
  25.   Please, *carefully* read this manual. Do not write me email with
  26. questions answered in here, as such letters are going to be ignored: I
  27. have too many other things to do to answer the same questions over and
  28. over again. 
  29.  
  30.   ColEm is a portable emulator of the old ColecoVision videogame console 
  31. written in C. You can always get the latest ColEm source code, binaries, 
  32. and support files from
  33.  
  34.      http://www.freeflight.com/fms/ColEm/
  35.  
  36. Another Coleco-related archive is located at
  37.  
  38.      ftp://ftp.komkon.org/pub/Coleco/
  39.  
  40.   There are versions of ColEm for Amiga, Macintosh, and IBM PC (both
  41. MeSsyDOS and Windoze). Following people are maintaining ports of ColEm to
  42. these systems:
  43.  
  44. Amiga:      Hans Guijt [jguijt@wi.LeidenUniv.nl]
  45. MSDOS:      Marcel de Kogel [m.dekogel@student.utwente.nl]
  46. Windows:    Neal Danner [neald@beta.datastorm.com]
  47. Macintosh:  Alan Steremberg [alans@umich.edu]
  48.             John Stiles [jstiles@cello.gina.calstate.edu]
  49.  
  50.   If you would like to port ColEm to another system, or make changes in
  51. ColEm's code *please*, contact me by email or some other means. Note, that
  52. ColEm source code is freely distributable, but it is *not* public domain.
  53. You can not use it in commercial purposes unless you contact me to arrange
  54. the conditions of such usage and get my permission. Feel free to look at
  55. existing drivers as well as at other code. More explanations follow. 
  56.  
  57.   The ColEm source code distribution includes C sources for a portable Coleco
  58. emulator, and screen/keyboard drivers for Unix/X and MSDOS. ColEm has been
  59. tested on following Unix systems: 
  60.  
  61. FreeBSD  Linux  SunOS  Solaris  AIX  HP-UX  Irix
  62.  
  63.  
  64.  
  65.                      * FREQUENTLY ASKED QUESTIONS *
  66.  
  67. 1. What is the complete list of command line options of ColEm?
  68.   Use -help option. It will tell ColEm to display all options available in 
  69. your version. Following are the currently available options:
  70.  
  71. -verbose <level>    - Select debugging messages [1]
  72.                       0 - Silent       1 - Startup messages
  73.                       2 - VDP         16 - Illegal CPU ops
  74. -ifreq <frequency>  - Set external interrupts frequency [50Hz]
  75. -iperiod <period>   - Set internal interrupts period [10000ops]
  76. -uperiod <period>   - Number of interrupts per screen update [2]
  77. -help               - Print this help page
  78. -autoa/-noautoa     - Autofire/No autofire for button A [-noautoa]
  79. -autob/-noautob     - Autofire/No autofire for button B [-noautob]
  80. -logsnd <filename>  - Write soundtrack to a file [off]
  81. -trap <address>     - [DEBUG] Trap execution when PC reaches address [FFFFh]
  82. -shm/-noshm         - [UNIX] Use/don't use MIT SHM extensions for X [-shm]
  83. -saver/-nosaver     - [UNIX] Save/don't save CPU when inactive [-saver]
  84.  
  85. 2. What are the keys used in ColEm?
  86.  
  87.   [SPACE] - Fire1 button (also: A,S,D,F,G,H,J,K,L)
  88.   [LALT]  - Fire2 button (also: Z,X,C,V,B,N,M)
  89.   [0]-[9] - Digit buttons
  90.   [-]     - # button
  91.   [=]     - . button
  92.   [ESC]   - Quit emulation (also: [F12])
  93.  
  94.   [SHIFT] and [CAPSLOCK] switch between joypads
  95.  
  96.   [F1]    - Turn tracing on/off (in DEBUG mode)
  97.  
  98. 3. Why is the emulator so slow on my PC?
  99.   Because your PC is too slow to run it. The emulator is written entirely
  100. in C language and therefore is quite slow. Although it works on 486/33 and
  101. even 386/33 PCs, it runs best on a Pentium/90 or a DEC Alpha/150. You can
  102. try to speed it up by increasing -uperiod value controlling the number of
  103. interrupts between screen updates to 3-6, and by decreasing -iperiod value
  104. controlling the number of CPU cycles between interrupts to 2000-5000. 
  105.  
  106. 4. Where do I get the software?
  107.   ftp://altair.komkon.com/pub/Coleco/
  108.  
  109. 5. Where is the sound?
  110.   Sound is only implemented in the Macintosh version of the emulator
  111. and the DOS version.
  112.  
  113. 6. Can I compile the emulator with my Borland/Turbo C compiler?
  114.   You can, given that your compiler creates executables using flat 32bit 
  115. memory model. Two PC compilers which do that are WATCOM (using DOS4GW DOS 
  116. extender) and GCC (using DJPP extender). The only 32bit Borland/Turbo C
  117. compiler that I'm aware is for Windows though.
  118.  
  119. 7. I can't get some ROM images to work with the emulator.
  120.   Try increasing -iperiod value to 10000 and higher. If you can't get ROM
  121. image to work, send it to me for analysis. 
  122.  
  123. 8. Is it legal to spread cartridge ROMs?
  124.   NO. Nobody seems to care though, mainly because there is no profit to be
  125. made on these ROMs any longer. Nevertheless, be aware of the fact that by
  126. using commercial software you haven't bought, you are commencing an act of
  127. piracy. Not that I care, anyway... 
  128.  
  129. 9. When compiling emulator under Unix, I get "undefined name" errors.
  130.   This means that your linker can not find the libraries necessary for the
  131. emulator (namely, libX11.a and libXext.a) or some additional libraries
  132. (like libsocket.a and libnsl.a) are required. Find these libraries in your
  133. system and modify the Makefile so that the final invocation of the C
  134. compiler has "-L<path_to_libs>" options. If you have no libXext.a library,
  135. try #undefining MITSHM option. 
  136.  
  137. 10. When starting emulator under Unix, I get X_ShmAttach error.
  138.   You are probably trying to run the emulator on a remote Xterminal while
  139. it attempts to use shared memory for interfacing with X. Use -noshm option
  140. to tell it not to use shared memory. 
  141.  
  142. 11. The emulation starts under Unix, but then I get X_PutImage error.
  143.   Unix/X version of the emulator currently needs 256-color X. Neither
  144. 2-color nor TrueColor Xterminals will work with the drivers included into
  145. the "official" distribution. 
  146.  
  147. 12. I start the Unix version of the emulator but the window stays black.
  148.   Some other X application took over all available colors so that the
  149. emulation could not allocate any for itself. Check if you run XV,
  150. Netscape, or something similar. 
  151.  
  152.  
  153.  
  154.                          * COMPILATION TIPS *
  155.  
  156.   If you are compiling the emulator under Unix, use Makefile. Notice that
  157. #define UNIX is present in this case. 
  158.   The emulation is written in fairly portable C code and may therefore be
  159. compiled with any decent ANSI C compiler. It relies on a flat 32bit memory
  160. model though, so Borland compilers will choke on it. Standard CC or GCC
  161. should do the job under Unix, although beware of GCC code generation
  162. bugs. If you are working under MeSsyDOS, use WATCOM C which is known to
  163. work. Under (God prohibit) Windows, use Borland C++ which has 32bit
  164. compilation model. On Amiga, use SAS/C. On Macintoshes, use Metrowerks C. 
  165.   If you are using an Intel-based computer or any other machine which has
  166. least-significant-byte-first data layout (for example, DEC Alpha), insert
  167.  
  168.                 #define LSB_FIRST
  169.  
  170. in the beginning of Z80.h file. The emulator will not work otherwise.
  171.   If you put
  172.  
  173.                 #define DEBUG
  174.  
  175. in the beginning of Z80.h, the emulator will print debugging information
  176. about CPU registers after executing each command. You can turn debugging
  177. on and off by setting Trace variable to 1 and 0 accordingly. Also, by
  178. setting Trap variable to some address you will make it start tracing when
  179. PC reaches this address (-trap option).
  180.   When you port the program to a new machine, you have to write a set of
  181. drivers for keyboard, sprites, and all the screen modes you want to
  182. emulate.  The emulator comes with a set of drivers for XWindows system.
  183. The common code for these drivers is located in Common.h and can be used
  184. for other systems too. Screen drivers use simple XSIZE*YSIZE array of
  185. bytes to generate image, so in most cases you will only need to adjust
  186. these drivers to your own needs. Note that the X11 drivers use so-called
  187. MIT Shared Memory Extension for fast transfers from buffer to a window. If
  188. you do not have MIT SHM extension in your system, remove
  189.  
  190.                 #define MITSHM
  191.  
  192. You can also turn MITSHM off (for example, if you use remote X terminal)
  193. by setting UseSHM variable to 0 before starting the emulation (-noshm
  194. option). 
  195.  
  196.  
  197.  
  198.                           * CODE STRUCTURE *
  199.  
  200.   Several other variables control the behaviour of the emulator. All of
  201. them should be set before starting the emulation in order to take effect: 
  202.  
  203. Verbose = 0..31
  204.   Defines amount of debugging information printed by emulator. Default 
  205.   value is 1. Each bit of this variable enables printing of some kind
  206.   of debugging info (VDP,CPU,memory,etc.).
  207. IPeriod = 1000..50000
  208.   Defines how many CPU commands should be executed between two interrupts. 
  209.   Normal interrupt rate is 60Hz for NTSC systems or 50Hz for PAL systems. 
  210.   Default value of IPeriod is 10000.
  211. CPURunning = 0/1
  212.   Set this variable to 0 to stop CPU and exit the emulation.
  213. AutoA = 0/1
  214.   Emulate autofire on the first fire button. Default value is 0.
  215. AutoB = 0/1
  216.   Emulate autofire on the second fire button. Default value is 0.
  217. SndName = "filename"
  218.   When SndName is not NULL, ColEm will open a file with this name, and 
  219.   save the soundtrack into it. The default value is NULL.
  220. Trace = 0/1
  221.   Print debugging information about CPU state. Default value is 1. 
  222.   #define DEBUG should be present in order to use this option. Tracing 
  223.   can be turned on and off during execution, for example, in keyboard
  224.   driver. 
  225. Trap = 0x0000..0xFFFF
  226.   Automatically start tracing when PC reaches given address. #define 
  227.   DEBUG should be present in order to use this option. 
  228. UPeriod = 1..10 
  229.   Defines how many interrupts should pass between two consequent screen
  230.   updates. Default value of UPeriod is 2.
  231. CartName = "cartridge.file"
  232.   Name of a .ROM file to load. Default value is "CART.ROM". This variable 
  233.   is ignored if no file exists. 
  234. UseSHM = 0/1
  235.   Use MIT SHM extension in X11 screen drivers. Default value is 1. 
  236.   #define MITSHM should be present in order to use this option. 
  237.  
  238.   In order to run the emulation:
  239.   
  240.   1. Set all necessary variables.
  241.   2. Initialize screen and keyboard drivers. In the case of X11 drivers, 
  242.      it is done by calling InitMachine() implemented in Unix.c and 
  243.      returning 1 on success or 0 otherwise.
  244.   3. Call StartColeco().
  245.   4. Call TrashColeco().
  246.   5. Shut down screen and keyboard (in X11 case, by calling TrashMachine()).
  247.   6. Exit the program.
  248.  
  249.   Take a look at ColEm.c to see an example of a sequence explained above.
  250.  
  251.  
  252.  
  253.                            * THANKS TO... *
  254.  
  255. o Hans Guijt [.NL]
  256. o Marcel de Kogel [.NL]
  257. o Neal Danner [USA]
  258. o Alan Steremberg [USA]
  259. o John Stiles [USA]
  260.  
  261. ...and to all people who helped me with advices, information, ROM images, 
  262. and encouragment.
  263.  
  264.  
  265. Marat.
  266.